@npmcli/fs

What is @npmcli/fs?

The @npmcli/fs package is a file system utility library that provides a set of asynchronous file system methods. It is designed to offer more convenient and higher-level operations for interacting with the file system in Node.js applications. This package is particularly useful for tasks like reading, writing, and manipulating files and directories in a way that's compatible with the rest of the npm CLI ecosystem.

What are @npmcli/fs's main functionalities?

Reading files

This feature allows you to asynchronously read the contents of a file. The code sample demonstrates how to read a file and handle the promise returned by the readFile method.

const { readFile } = require('@npmcli/fs');
readFile('path/to/file.txt', 'utf8').then(contents => {
  console.log(contents);
}).catch(error => {
  console.error('Error reading file:', error);
});

Writing files

This feature enables you to write data to a file asynchronously. The code sample shows how to write a string to a file and handle the promise to catch any errors.

const { writeFile } = require('@npmcli/fs');
const content = 'Hello, world!';
writeFile('path/to/file.txt', content, 'utf8').then(() => {
  console.log('File written successfully');
}).catch(error => {
  console.error('Error writing file:', error);
});

Removing files

This feature provides a way to asynchronously remove a file. The code sample illustrates how to delete a file and handle the promise to catch errors.

const { unlink } = require('@npmcli/fs');
unlink('path/to/file.txt').then(() => {
  console.log('File removed successfully');
}).catch(error => {
  console.error('Error removing file:', error);
});

Other packages similar to @npmcli/fs

fs-extra

fs-extra is a popular npm package that extends the built-in Node.js fs module. It adds file system methods that aren't included in the native fs module, such as copying directories and files, removing directories, and ensuring directories exist. Compared to @npmcli/fs, fs-extra offers a broader set of file system operations and is widely used for its convenience methods.

rimraf

rimraf is a Node.js package that provides a simple way to remove files and directories, mimicking the UNIX command `rm -rf`. It's specifically focused on deletion operations, making it more specialized compared to @npmcli/fs, which offers a variety of file system operations including reading, writing, and removing files.

README

@npmcli/fs

polyfills, and extensions, of the core fs module.

Features

• fs.cp polyfill for node < 16.7.0
• fs.withTempDir added
• fs.readdirScoped added
• fs.moveFile added

fs.withTempDir(root, fn, options) -> Promise

Parameters

• root: the directory in which to create the temporary directory
• fn: a function that will be called with the path to the temporary directory
• options
  • tmpPrefix: a prefix to be used in the generated directory name

Usage

The withTempDir function creates a temporary directory, runs the provided function (fn), then removes the temporary directory and resolves or rejects based on the result of fn.

const fs = require('@npmcli/fs')
const os = require('os')

// this function will be called with the full path to the temporary directory
// it is called with `await` behind the scenes, so can be async if desired.
const myFunction = async (tempPath) => {
  return 'done!'
}

const main = async () => {
  const result = await fs.withTempDir(os.tmpdir(), myFunction)
  // result === 'done!'
}

main()

fs.readdirScoped(root) -> Promise

Parameters

• root: the directory to read

Usage

Like fs.readdir but handling @org/module dirs as if they were a single entry.

const { readdirScoped } = require('@npmcli/fs')
const entries = await readdirScoped('node_modules')
// entries will be something like: ['a', '@org/foo', '@org/bar']

fs.moveFile(source, dest, options) -> Promise

A fork of move-file with support for Common JS.

Highlights

• Promise API.
• Supports moving a file across partitions and devices.
• Optionally prevent overwriting an existing file.
• Creates non-existent destination directories for you.
• Automatically recurses when source is a directory.

Parameters

• source: File, or directory, you want to move.
• dest: Where you want the file or directory moved.
• options
  • overwrite (boolean, default: true): Overwrite existing destination file(s).

Usage

The built-in fs.rename() is just a JavaScript wrapper for the C rename(2) function, which doesn't support moving files across partitions or devices. This module is what you would have expected fs.rename() to be.

const { moveFile } = require('@npmcli/fs');

(async () => {
	await moveFile('source/unicorn.png', 'destination/unicorn.png');
	console.log('The file has been moved');
})();

Changelog

3.1.1 (2024-05-03)

Documentation

• 2cb7474 #91 fix the example for readdirScoped (#91) (@aminya)

Chores

• 237e7c6 #106 bump @npmcli/template-oss to 4.22.0 (@lukekarrys)
• 456d343 #106 postinstall for dependabot template-oss PR (@lukekarrys)
• 5b0f7c6 #105 bump @npmcli/template-oss from 4.21.3 to 4.21.4 (@dependabot[bot])